#!yaml-readme -p *.yaml --output what/tw.md
> 本文主要讨论在开源项目中的 Technical Writter（以下简称 TW）

## 基本要求
众所周知，开源是面向全球的，通常都会对英语写作能力有着较高的要求。

下面是部分团队对英文的要求：

* [通过英语专业八级考试（TEM-8，Test for English Majors-Band 8）](https://baike.baidu.com/item/%E8%8B%B1%E8%AF%AD%E4%B8%93%E4%B8%9A%E5%85%AB%E7%BA%A7%E8%80%83%E8%AF%95/6297184)

在不少的开源团队中，研发、TW 都会首先输出英文资料（文档、教程、博客等），而其他语言（中文、小语种）可能会考虑通过社区协作、内部员工等方式来输出。

## 常规工作
TW 最基本的工作可以包括以下三部分：

* 技术文档输出，这一点基本会随着开源项目的 feature 来迭代
* Release notes、Changelog
* 教程（文字、视频）

对于技术文档来说，要比其他两个相对复杂一些，往往需要 TW 对所负责的开源项目在技术层面有相对比较深入的了解，至少需要能够做到：了解必要的技术背景、简单的环境搭建、熟练地使用项目完成基本的 use case 等。除技术本身外，由于开源项目通常都会按照版本进行划分，而文档自然也需要提供对应的版本。

在语言之外，以下是开源项目中的主流技术搭配使用，也几乎可以认为是对 TW 的基本要求：

* [熟练使用 GitHub](https://skills.github.com/)，以及可以在终端熟练地使用 [git](https://git-scm.com/) 命令
* [Markdown](https://www.markdownguide.org/basic-syntax/) 常见语法的使用
* [Hugo](https://github.com/gohugoio/) 等静态网站构建工具
* Linux 基本操作

## 更多工作
在 TW 团队规模较大的情况下，往往会有更细致的分工，以及更多的职责。例如：社区具有一定规模的请下，TW 可能需要组织社区共建者（Contributor）参与到多语言的共建（Contribution）中，甚至还可能会成立、组织 SIG（Special Intested Group），并定期组织社区例会。

这时候，作为 TW 仅仅能完成技术文档的输出可能就显得不够了，熟悉、践行开源理念，并与开源同行进行更多的交流、互动会显得日益重要。如果说，某个开源项目的共建者（Contributors）都隶属于某家商业公司的话，从开源的角度来看这个项目其实是失败的，即便这个项目有着再多的 star 数，对于代码或文档类项目都是如此。

## 协作
作为 TW 往往需要与不同角色的人进行合作，例如：产品经理、研发、测试、运营、市场等，尤其会和研发有着紧密的协作。在与不同角色、背景的人合作时，如果能了解、掌握一些沟通技巧时，往往可以有事半功倍的效果。以下，针对不同角色的人合作，提供一些技巧。

在国内很多人交流后，有个相对普遍的观点是：研发往往不太喜欢写文档，工作安排普遍紧张（难以抽出时间来），写的文档容易出现省略基本的技术背景介绍等等。（在没有数据统计的情况下，这些论断可能是相对主观的，仅供参考）针对以上提出来的一些问题，笔者认为都是有相应原因的，了解这些背后的缘由，则可以帮助我们更好地互相理解、协作。

选择从事研发工作的人，往往对逻辑性的问题比较有兴趣，而在他们的职业生涯中如果没有对文档编写有过硬性要求的话，随着时间的推移，对文字编写、自然语言的技能则逐渐弱化。而从心理学的角度来看，人们通常会不由自主地选择逃避自己的“短板”。这可能是“研发不爱写文档”的一个典型原因。

而对于研发工作量大、没时间写文档等，则是一个具体的现象，并不是 TW 在与研发合作编写文档时遇到的困境的原因。假如，研发负责人（甚至在整个公司、团队的理念、文化中）并不认为文档属于软件交付过程中不可缺少的一部分，或者是认为研发只要输出代码即可，那么，在安排工作时就不会给文档编写预留足够的时间。在这样的公司理念的影响下，研发人员就会自然地以工作繁忙为理由选择推脱甚至拒绝相应的文档工作。简单来说，这是自上而下产生的问题。

至于文档编写过程中，可能会缺少一些必要的技术背景介绍，则也许是由于缺少训练而导致的一个普遍性的问题。除非是有着非常资深背景的人，在很多情况下，研发人员不会有编写大量文档的机会，很难在短时间内克服；这也正是需要专业 TW 加入的理由。

从每一位 TW 和整个公司、团队的角度，可以考虑不同的解决方案：

在自上而下管理风格的团队中，想要通过提出建议而改善情况有可能会逐渐演变为你讨厌团队的导火索。但笔者追求的是，把感性的烦恼转换为理性的思考，以更加健康、可持续的姿态来对面问题、解决问题。当然，这里不是反对大家给团队提出你的宝贵建议，而提倡的是以“无心插柳”的心态来提建议。以人为本，把与你合作的研发当做良师益友来看，他（她）也会有职业上、工作上的困扰，试着去了解并与之一起解决，至少可以推心置腹地进行几次沟通；相信在帮助对方过程中，他（她）也会尊重、理解、配合你的工作。

如果有能力从整个公司、团队角度来改善、解决这个问题的话，可以考虑强制约束研发要写文档，以及在新人招聘的流程中加上对文档技能的考察，并告知公司对文档编写的相关规定。当然，团队管理本身是一个非常复杂的话题，这里无法一一展开，实际落地过程中也会遇到各种各样的问题，坚持做对的事情并及时复盘（review）可以助你一臂之力。

## 成长路径
对于 TW 的成长路径，笔者认为除了可以从初级、中级、高级这些职级上来衡量，也可以从对 TW 这个行业甚至跨行业的视角从细节到整体再到细节的来考量，稍微具体一点的话，可以参考下面的表述：

* 完成团队分配到自己的任务
* 能够发现本职工作以外的问题并协同解决
* 能够组织同事（同行）解决更大层面上的问题
* 开始关注、了解整个行业的现象、事件与发展趋势
* 逐渐能够在行业交流（会议、论坛、社交网络）中发表自己的观点
* 未知的跨域探索

## Credit

Thanks for all those friends who helped me with this project.

* {{gh "Sherlock113" true}}
* {{gh "sylviababy" true}}
* {{gh "hf400159" true}}
